home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / libs / rawkey-0.2 / rawkey-0 / rawkey / README < prev    next >
Encoding:
Text File  |  1994-10-24  |  6.3 KB  |  185 lines
  1. Rawkey library v0.2
  2. -------------------
  3.  
  4. This is an attempt to make the use of raw keyboard mode for games
  5. easier. It hides the necessary ioctl()'s somewhat, and hopefully makes
  6. the whole process a bit less painful. The library assumes you are
  7. using svgalib.  (If you look in vga.c from [s]vgalib and check out the
  8. bit where it changes the termio settings, for text mode you'd need to
  9. do something along those lines before calling rawmode_init().)
  10.  
  11. VT switching can be arranged now, but is disabled by default.
  12.  
  13.  
  14. Installation
  15. ------------
  16.  
  17. To install, do a 'make install' as root. This will install 'rawkey.h' in
  18. /usr/include, 'librawkey.a' in /usr/lib, and compile a simple test program
  19. (using svgalib), called 'testprog'.
  20.  
  21. After that, check 'testprog' works by running it, using the cursors to move
  22. the dot around, and Esc to quit. Check that holding, say, up and left cursor
  23. keys at the same time gives a diagonal, and also check the response is
  24. instant with no keyboard repeat delays.
  25.  
  26.  
  27. How to use the Rawkey library
  28. -----------------------------
  29.  
  30. The important functions to know about are:
  31.  
  32.  
  33. int rawmode_init()
  34.  
  35. call this to start using raw mode.
  36. returns 1 if ok, 0 on error.
  37. You should be in graphics mode before calling this, if using svgalib. A
  38. typical startup sequence might go:
  39.  
  40.     main()
  41.     {
  42.     vga_init();
  43.     vga_setmode(G320x200x256);
  44.     rawmode_init();
  45.     ...
  46.  
  47.  
  48. void rawmode_exit()
  49.  
  50. call this to resume normal operation.
  51. Although it's not actually necessary, it's probably nicest to call this just
  52. before ending with 'vga_setmode(TEXT)' or whatever.
  53.  
  54. WARNING: Make *sure* you are out of RAW mode before exiting, or believe me
  55. you'll regret it! Consider setting up signal handlers for things like
  56. SIGSEGV or whatever just in case.
  57.  
  58.  
  59. void scan_keyboard()
  60.  
  61. this handles scancode reading from the keyboard, which you shouldn't
  62. *directly* worry about. You need to call this every so often - the easiest
  63. way is to call it whenever you would ordinarily call, say, vga_getch(). Note
  64. that this function has no return value - call it first then use
  65. is_key_pressed() to check the status of any individual key.
  66.  
  67. Say if you would ordinarily use something like this for a 'press space'
  68. type pause:
  69.  
  70.     while(vga_getch()!=32);
  71.  
  72. you would now do:
  73.  
  74.     [insert '#include <unistd.h>' at the top]
  75.  
  76.     do
  77.           {
  78.       usleep(10000);    /* check at most every 1/100th of a second */
  79.       scan_keyboard();
  80.       }
  81.     while(!is_key_pressed(SPACE_BAR));
  82.  
  83. i.e. scan_keyboard() goes where you would normally put a vga_getch(), but
  84. when you need to test if a key was/is pressed, you use is_key_pressed() (see
  85. below). The usleep() is to prevent burning unnecessary CPU time, as
  86. scan_keyboard() is non-blocking, i.e. it doesn't wait for a keypress.
  87.  
  88.  
  89. int is_key_pressed(int scancode)
  90.  
  91. this tells you if a specific key is pressed.
  92. Returns 1 if true, 0 otherwise
  93. The arg is the scancode of the key. You don't really need to know about
  94. that, what you *do* need to know is that the following symbols are
  95. pre-defined and can be used as args to is_key_pressed():
  96.  
  97.     ESCAPE_KEY, ENTER_KEY, BACKSPACE, TAB_KEY
  98.     LEFT_SHIFT, RIGHT_SHIFT, LEFT_CTRL, LEFT_ALT    (see below)
  99.     FUNC_KEY(x)    (x ranging from 1 to 12)
  100.     CURSOR_LEFT, CURSOR_RIGHT, CURSOR_UP, CURSOR_DOWN, KEYPAD_CENTER
  101.     INSERT_KEY, DELETE_KEY, HOME_KEY, END_KEY, PAGE_UP, PAGE_DOWN
  102.     CAPS_LOCK, NUM_LOCK, SCROLL_LOCK
  103.     GRAY_PLUS, GRAY_MINUS, GRAY_MULTIPLY, GRAY_DIVIDE    (see below)
  104.  
  105. Note the following:
  106. 1. 'LEFT_CTRL' and 'LEFT_ALT' actually cover both ctrl's and alt's.
  107.    'LEFT_SHIFT' and 'RIGHT_SHIFT' do cover the respective shift's, however.
  108. 2. 'GRAY_MULTIPLY' is also generated by PrintScreen.
  109. 3. There is no reliable way to check for PrintScreen or Pause yet. Sorry.
  110. 4. KEYPAD_CENTER is the '5' in the centre of the numeric keypad.
  111. 5. If the key you want to check for is a letter or number key,
  112.    use scancode_trans() as shown below in the 'Ctrl-X' example.
  113. 6. If the key you want to check for is shifted, think about how many keys
  114.    you're pressing to get that key, then see 7 below.
  115. 7. If you want to check for, say, Ctrl-X, you should check them as two
  116.    keys being simultaneously pressed, i.e. do:
  117.  
  118.      if(is_key_pressed(LEFT_CTRL) && is_key_pressed(scancode_trans('x')))
  119.     ...
  120.  
  121. 8. If the key you want to check for isn't covered by any of the above,
  122.    don't use it. :)  It probably won't stay the same between different
  123.    national keyboards anyhow, so it's a bad move to check for it.
  124. 9. In a similar vein, games writers please allow redefinable keys! It's a
  125.    bit of a pain, but is a godsend for people who hate your wonderful
  126.    perfect choice of keys :) or have, say, an AZERTY keyboard which might
  127.    screw those keys' arrangement up badly.
  128.  
  129. See testprog.c for a fuller example of how this function should be used.
  130.  
  131.  
  132. int is_any_key_pressed()
  133.  
  134. this is a function that checks if any key is pressed (including shifts etc.)
  135. to save you having to do it for those 'press any key' jobs.
  136. Returns 1 if true, 0 otherwise.
  137.  
  138.  
  139. int scancode_trans(int asciival)
  140.  
  141. effectively returns the scancode for the given ASCII
  142. Also returns -1 if none found.
  143. Use this with is_key_pressed to tell if a letter or number key is pressed -
  144. e.g. to tell if the Q key is pressed (must be lowercase):
  145.  
  146.     if(is_key_pressed(scancode_trans('q'))) ...
  147.  
  148. This routine uses a copy of keymap 0 (no modifiers) as held by the kernel;
  149. see loadkeys(1) and keytables(5) for more info.
  150.  
  151.  
  152. void set_switch_functions(void (*off)(void),void (*on)(void))
  153. void allow_switch(int on)
  154.  
  155. These allow you to setup console switching via alt-Fn. Call these
  156. like:
  157.  
  158.     set_switch_functions(undrawfunc,redrawfunc);
  159.     allow_switch(1);
  160.     ...
  161.  
  162. ...where undrawfunc() puts the screen in text mode, and redrawfunc()
  163. goes back to graphics and redraws the screen. If the user presses alt
  164. and a function key this is detected in scan_keyboard(), which will
  165. effectively block until the console is returned to.
  166.  
  167.  
  168. This probably all looks rather confusing, so potential games writers should
  169. look at testprog.c and rawkey.h for more clues as to how to go about using
  170. raw keyboard mode via this library.
  171.  
  172.  
  173. Epilogue
  174. --------
  175.  
  176. I welcome bug reports, suggestions for improvements, anything really.
  177. (Please bear in mind, however, that this library is only intended for the
  178. simple keyboard use made by games. And IMHO, only games and emulators should
  179. ever need to use RAW mode.)
  180.  
  181. If you need any help using it, email me and I'll try to assist you.
  182.  
  183. Cheers,
  184. - Russell Marks (mr216@gre.ac.uk)
  185.